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1.0 PREFACE 



1.0 £E££A££ 



The CY8IL source code formatter described in this document is 
based on past experiences developing and using comparable 
formatters for the CYBILI and CYBILC languages* 



1.1 ££Q££.a£-fiGCyi3£MI 

This document is intended to contain information necessary to 
use the CYBIL formatter In an interactive or batch job* 

It is assumed that the reader is familiar with the CYBIL 
language and concepts of the NGS operating system* 



1.2 A££LICAaL£.aaaU!l£tiia 

CYBIL Language Specification (ARH2298) 
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2.0 INTRODUCTION 



2.0 imimqucuo!! 



The CYBIL formatter Is a utility used to format CYBIL sourc 
ode to maximize readability* It executes as a standalone 
roduct* 



2.1 ayaeaai 

The formatter provides a common tool for formatting CYBIL 
source code prior to compilation* CYBIL programs formatted by a 
common tool Mill be more consistent* readable and maintainable* 



2.2 Q¥£Smg 

The formatter is executed as an absolute file* Input and 
output for the formatter are specified with a NQS control card* 
Formatting may be controlled to a limited extent by the use of 
CYBIL pragmats* 
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The formatting conventions are mostly hard coded into the 
formatter with some conventions being alterable by the use of 
pragmats* 

3.1 IMEUI-EIL£_£ati¥£!iIiCm$ 

1) Source must be normal CYBIl input files (currently the NQS 
6/12 character set). 

21 Source must be legitimate CYBIL source* but is not 
necessarily a compilation unit* Common decks are 
formattable* 

3) Source file is assumed positioned and local* 

4! Multiple records on source file are formatted* 

5) Source line may be any length as formatter reads to 
end-of-l ine* 

3 . 2 Efl&a&ma-ayieu i-EiiE.XQ!i¥EtiiiQ&s 

1) All lines will be 79 characters or less unless altered by a 
pragmat* 

2) The character set output by the formatter will be identical 
to the Input file character set* 

3) The formatted output file is created as a local file and is 
not rewound before or after* 

4) The output file wilt always start with 1 blank line* 
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3.0 CONVENTIONS 

3.3 EaRaAIII&£-£Qii¥E!mQMS 

1) All keywords will be converted to upper case. The 
predefined data types like integer* char* cell* boolean* 
string* array* record* and set will always be in lower 
case. 

2) All programmer created identifiers will be converted to 
lower case. 

3) The case of strings and comments will not be altered* 

4) Comments starting at the left hand margin will not be 
formatted. 

5) Lines with the asterisk control character in column one are 
not formatted. These lines are assumed to be maintenance 
package control statements which will be satisfied before 
compi I ation. 

6) Blank or empty lines are retained. 

7) Blanks are squeezed to 1 except within strings and 
comments. 

8) A J (semicolon) will cause a new line to be started. If a 
trailing comment follows on that same line* it will remain 
there. 

9) A space will be added before and/or after certain 
delimiters. Such as: t and 1 on attribute lists* the 
operators* etc* 

101 Keywords that start or terminate a structured statement will 
start a new I ine. 

Ill Keywords that form a structured statement will cause 
following statements to have a margin of 2 greater than the 
line that contains the keyword. Keywords that terminate a 
structured statement will decrease this margin by 2. The 
maximum margin will be 40. 

12) If there is no blank line before a VAR* TYPE* CONST* or 
PROCEDURE statement* or label* one will be put there. A 
blank line will separate a local variable declaration from 
the procedure statement list. 
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3,0 CONVENTIONS 

13) Each parameter declaration will start a new line when they 
appear within a PROCEDURE declaration* A value attribute 
will have a margin six spaces greater than the margin for 
the PROCEDURE statement. The maximum margin will be 40* 

14) Identifiers defined in TYPE* VAR* and CONST statements will 
each start on a new line* 

15) Labels are backed up 2 columns from current margin and are 
at one on a 1 ine* 

16) If comments nee4 to be separated across lines* they will be 
separated at a blank and subsequent lines will be lined up 
with the original line* 

17) If comments starting at the left hand margin are too long* 
they are continued at the left hand margin of succeeding 
tines until the comment is completed* 

18) The left hand column defaults to 1 unless altered by a 
pragmat* The starting margin is equal to the left hand 
cot umn* 

NOTE* The first input line is given a margin of 1* 

19) Pragmats that are processed by the formatter take effect 
after their appearance in the source* 

20) The formatter checks column one of the input stream and if 
it is non-numeric or the asterisk control character* the 
information is assumed to be text* 

21) The formatter stops execution and outputs an appropriate 
message upon detecting the first syntax error* The error 
flag job control register is set to 13B (forced error)* 

22) The THEN clause of the IF statement will normally be on the 
same line as the IF* space permitting* 

23) The ELSE and IFEND clauses are aligned with the IF 
statement* 

24) CASE selection specs will have the same margin as their 
associated CASE statement* 

25) Statements that exceed the length of a line will be 
continued on the following line with a 6 character 
i ndentat i on* 
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3.0 CONVENTIONS 

3.3 FORMATTING CONVENTIONS 



26) Long strings that do not fit on a single line will be split 
and the CAT operator generated. 

27) A label Milt be filled in on ending delimiters of labeled 
structured statements* and exit* cycle* procend* modend and 
funcend statements. 



3.4 iUSSESIiOMl 

The following list of formatting features will not be done by 
the interim formatter* but should be strongly considered for the 
ultimate CY8IL formatter. 

o Verifying that if the 4th character of a name is a % sign* 
then the 3rd character must conform to the C180 System 
Interface Standard. 

o Recognition and justification of comments within a comment 
block. 

o Develop a method of highlighting changes In flow of execution 
caused by the EXIT* CYCLE and RETURN statements. 

o Investigate readability of tabbing the •*• in a type* 
variable* field or parameter specification to a fixed 
posi tion. 

o Enhanced Interface to SCU* 

o Precede a comment block with 2 blank lines and follow it with 
1 blank line. A comment block is 1 or more lines of 
comments. 
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4,0 PRAGHATS 



4.0 ERASMUS 



Pragmats appearing in the source are used to control the CYBIL 
formatter and will be copied to output to provide a graceful 



teans of reformatting, 

4.1 £xaiueaA£Mis 



These CYBIL pragmats control the CYBIL compiler as wet! as the 
formatter and are treated similarity* 



4.1*1 ??RIGHT s» N?? 



For the CYBIL formatter* this pragmat is used to specify 
maximum output line length with n >* 72 and <» 110. The default 
value is 79* This pragmat indicates to the CYBIL compiler the 
maximum length of a source line* 



4.1*2 ??LEFT J* N?? 



Used to make the CYBIL compiler and formatter Ignore any 
foreign data outside the CYBIL syntax* For the formatter* this 
pragmat indicates left hand output column and starting margin* 
The default value is 1* The foreign data which exists in the 
ignored column positions will be copied to the output file* 

4.2 £QaaAII£&-£EAfiaAI 

This pragmat controls only the CYBIL formatter and is not 
processed by the CYBIL compiler* 
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4.0 PRAGMATS 
4.2.1 SYNTAX 



4.2.1 SYNTAX 

<fornatter pragmat statement> n* ??<formatter pragmat>?? 

<for«atter prag»at> st* EtSI Ktoggle setting 1 1 st> I 

<toggie setting llst> u a <toggle setting> C»<toggle setting>l 

<toggle setting> ss* <toggie identifier> J* <condition> 

<toggle identifier> ?s* EOESAI 

<condition> s:» Q9 5 Q££ 

4.2.2 TOGGLE IDENTIFIERS 

o FORMAT 

Used to control formatting of all lines. Default is FORMAT s 
ON. 

FORMAT J» ON — Ail source lines are formatted. 

FORMAT J* OFF - No source lines are formatted. 
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5*0 USE OF FORMATTER 



5,0 ilSEJlE_£Q£Ji&IIEE 



Two methods of accessing the CY8IL formatter are described in 
this section* The formatter provided through the SES is more 
stable and more widely used* The formatter available through the 
project catalog (tP3) is more dynamic and is updated more 
frequently. 

5.1 i££_£EQ££QUE£-I!iI£E£A££ 

An SES procedure interface is available for accessing the 
CYBIL formatter and is described in S£S»s User Handbook 
URH1833). 



5.2 CiaiUEQEMXIEE-ULL 

The CY8II formatter can be executed as an absolute file* 

ATTACH* CY8F0RM/UN*LP3 

CYBFORMC(<I»f i I ename>1 tO0«f i lename>>3 

Is Specifies the name of the file to be formatted* If 

I is not specified* the name of the file is I* 

0* Specifies the name for the formatted file. If is 

not specified, the name of the file is 0. 

NOTE: I and may not use the same file name* 
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6,0 EXAMPLES 



6.0 £*AII£LES 



6*1 £Qli&£E_£EO£EAt! 



1) ??RIGHT s» 110?? 
MODULE Mil 

PROCEDURE Al; 
VAR is INTEGER? 
PROCEND Al; 
MQDEND Ml; 

Formatted iss 

??RIGHT s* 110?? 
MODULE »1; 

PROCEDURE al; 

VAR 

i * Integer; 
PROCEND all 
MODEND ml; 

2) ??RIGHT :« 72?? 
MODULE Ml; 

PROCEDURE A1J 
VAR 

I: INTEGER; 
CONST J»5; 
PROCEND All 
M3DEND Ml; 

Formatted iss 

??RIGHT s* 72?? 
MODULE »l; 

PROCEDURE al; 

VAR 

i s integer; 
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6.0 EXAMPLES 

6.1 SOURCE PROGRAM 



CONST 

PROCENO all 
MODENO all 



6.2 SAB£L£-£*££yiIQB 



G£T»I*SOURCE. 

ATTACH* CYBF0RH/UN*LP3. 

CYBFGRM. 

REPLACE*0*COMPILE. 

The file COMPILE wi II contain the formatted program found on 
file SOURCE. 



6.3 &£SSA£ES 

Messages are written to the OUTPUT file and the dayfile. The 
source line that caused the error message nil I normally be the 
last one on the output file. 

1) ***UNBALANCED BLOCK STRUCTURE*** 

Begin and end statements for structured statements do not 
match. 

Z) ***IMPR0PER PARAMETER LIST*** 

Something is wrong with a procedure definition statement. 

3) ***EXTRANEOUS RIGHT PARENTHESIS*** 
Right and left parens do not match. 

4) ***MISSING RIGHT PARENTHESIS*** 
Right and left parens do not match. 

5) ***IMPR0P£R CASE LABEL*** 
Improper case statement. 

6) ***IMPRQPER FORMAT TOGGLE*** 
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6»0 EXAMPLES 
6*3 MESSAGES 



Something is wrong with a format pragmat that the CYBIL 
formatter processes* 

7) ***IMPRGPER HEX CONSTANT*** 
Something is wrong with a hex constant* 

8) ♦♦♦IDENTIFIES TOO LONG*** 

Have an identifier greater than 31 characters* 
9} ***IMPR0PER STRING CONSTANT*** 

A quote is missing at EOL causing a syntactic error* 

10) ***PRAGMAT STRING TOO LONG FOR LINE*** 

The string in the titling pragmat does not fit on the line 
and cannot he continued* 

11) ***ILLEGAL CONTROL CARD KEYWORD*** 

A keyword other than I or was found on the control card* 
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